::::::::::::::::::::::::::::::::::::::::::::::::::::
::::::::::::::::::::::::::::::::::::::::::::::::::::
MS Agents and MS Office Characters
Accessing MS Agent and MS Office characters couldn't be easier if you use the comalspeech.dll made available to Liberty BASIC programmers through the generosity of John White. A tutorial for accessing and incorporating the MS Agent Merlin, using the Liberty BASIC v4 Lesson Browser format, can be found in the [Liberty BASIC Newsletter Issue #126]. Since the publication of that tutorial, [John White] has further enhanced his comal dll, the most current dll (April, 2005) being comalspeech.dll. The commands remain the same, though, and the lesson browser code in Issue #126 will work with either dll version.
While the MS Agent commands appear to work well with Merlin, attempts to select any other MS Agent have been inconsistent. The Open MS Agent command reads
sartn=SpeechOpen("Merlin")
function SpeechOpen(agentName$)
calldll #comal,"SPEECH_Open",agentName$ as ptr,SpeechOpen as long
end function
Substituting "Merlin" with the name of another MS Agent (e.g., Peedy or Genie) failed to yield the expected results. In most situations, it was still Merlin who appeared. On a rare occassion, another agent would appear. This problem became most evident during the [Liberty BASIC Chat Challenge]. [Rod] discovered that the dll was loading the default MS Agent as defined by a registry entry. Some joint [discussion] by Rod and John White revealed that the SpeechOpen() function did, indeed, load the default MS Agent, but that a second function, the SpeechOpenAgent() function could be used to select any available MS Agent. You may need to adjust the following acsPathName$ for your computer.
sartn=SpeechOpenAgent("Genie", "C:\WINDOWS\msagent\chars\genie.acs")
function SpeechOpenAgent(agentName$,acsPathName$)
calldll #comal,"SPEECH_OpenAgent",agentName$ as ptr,acsPathName$ as ptr,SpeechOpenAgent as long
end function
The comalspeech dll can access MS Office characters as well. Use the same SpeechOpenAgent() function, making sure the acsPathName$ is a valid path leading to an MS Office character.
sartn=SpeechOpenAgent("Rocky", "C:\Program Files\Microsoft Office\OFFICE11\rocky.acs")
function SpeechOpenAgent(agentName$,acsPathName$)
calldll #comal,"SPEECH_OpenAgent",agentName$ as ptr,acsPathName$ as ptr,SpeechOpenAgent as long
end function
Remember to always close any MS Agents and MS Office characters opened with the comal close function SpeechClose()
rtn=SpeechClose() function SpeechClose() calldll #comal,"SPEECH_Close",SpeechClose as Long end function
The following demo allows you to find installed MS Agents and MS Office characters on your computer. Remember, you must have comalspeech.dll available in the folder from which this demo is run.
'Demo to find MSAgent Characters
Print "Please choose one set of characters"
Print "1) MS Office Characters"
Print "2) MS Agent Characters"
Print
Input "Your selection (1 or 2) > ";MSSel
If MSSel = 1 Then
'Valid Path for Windows XP Home Edition, MS Office 2003
acsPath$ = "C:\Program Files\Microsoft Office\OFFICE11"
Else
'Valid Path for Windows XP Home Edition
acsPath$ = "C:\WINDOWS\msagent\chars"
End If
'MSAgent file extension = .acs
MSAgentExt$ = "*.acs"
'Dim the arrays
Dim MSAgentPath$(10)
Dim MSAgentName$(10)
Dim Info$(10, 10)
'Retrieve the MSAgents in that sub folder
nAgents = nAgents(acsPath$, MSAgentExt$)
'If no agents found, then folder may be invalid
If nAgents = 0 Then
Print "In need of help finding path to MSAgent characters."
Filedialog, "Open MSAgent Character", "*.acs", UserPath$
If Lower$(Right$(UserPath$, 4)) = ".acs" Then
acsPath$ = ExtractPath$(UserPath$)
nAgents = nAgents(acsPath$, MSAgentExt$)
Else
Print "Unable to find MSAgent characters. Ending Demo."
End
End If
End If
'Display the MSAgents in that sub folder
Print
Print "Your choices are"
For i = 1 to nAgents
Print i, MSAgentName$(i)
Next i
Print
'Allow user to choose one
Print "MS Agent (1 - ";nAgents;"): ";
Input "";selAgent
MSAgentPath$ = MSAgentPath$(selAgent)
MSAgentName$ = MSAgentName$(selAgent)
Print
Print "MSAgentPath$ = ";MSAgentPath$
Print "MSAgentName$ = ";MSAgentName$
'Load comalspeech.dll
Open "comalspeech.dll" for DLL as #comal
sartn = SpeechOpenAgent(MSAgentName$, MSAgentPath$)
rtn = AgentSpeak("You may call me ";MSAgentName$;".", 1)
Print
Print "It is important to NOT end this program with"
Print "the Trapclose, but to PRESS RETURN first."
Print
Input "Press Return to End Program ";z$
rtn = SpeechClose()
Close #comal
Print
Print "Program has ended."
End
'nAgents Function based upon the fileExists Function found
'in the Liberty BASIC help file
Function nAgents(path$, fileName$)
Files path$, fileName$, Info$()
nAgents = Val(Info$(0, 0))
Redim MSAgentPath$(nAgents)
Redim MSAgentName$(nAgents)
For i = 1 to nAgents
MSAgentPath$(i) = path$;"\";Info$(i, 0)
MSAgentName$ = Word$(Info$(i, 0), 1, ".")
MSAgentName$(i) = Upper$(Left$(MSAgentName$, 1)) + _
Lower$(Right$(MSAgentName$, Len(MSAgentName$) - 1))
Next i
End Function
Function ValidateMSAgentFolder(path$)
Files path$, Info$()
ValidateMSAgentFolder = Val(Info$(0, 0))
End Function
Function ExtractPath$(FullPath$)
For i = Len(FullPath$) to 1 Step -1
If Mid$(FullPath$, i, 1) = "\" Then
Exit For
End If
Next i
ExtractPath$ = Left$(FullPath$, i - 1)
End Function
Function SpeechOpenAgent(agentName$, acsPathName$)
Calldll #comal, "SPEECH_OpenAgent", _
agentName$ as Ptr, _
acsPathName$ as Ptr, _
SpeechOpenAgent as Long
End Function
Function SpeechOpen(agentName$)
Calldll #comal, "SPEECH_Open", _
agentName$ as Ptr, _
SpeechOpen as Long
End Function
Function AgentSpeak(textString$, showAgent)
Calldll #comal, "AGENT_Speak", _
textString$ as Ptr, _
showAgent as Long, _
AgentSpeak as Long
End Function
Function SpeechClose()
Calldll #comal, "SPEECH_Close", _
SpeechClose as Long
End Function
FAQ: comalspeech.dll
Where can I get comalspeech.dll? [http://www.yoingco.com/YoingcoDLLs.zip]
What other comal dll's have been written by John White? comaldb.dll, comalexcel.dll, comalocr.dll, and comalword.dll. All comal dll's, as well as documentation and sample files, are included in the YoingcoDLLs.zip.
I see the talk bubbles, but I can't hear Merlin or the other agents speak. What gives? Audible speech requires the installment of a speech engine. To learn more about speech engines, read [Text to Speech with Liberty BASIC] by Stefan Pendl in the Liberty BASIC Newsletter Issue #118. MS Agent support files are downloadable at [http://www.microsoft.com/msagent/downloads/user.asp].
I can hear Merlin, Peedy and Genie, but the MS Office characters aren't audible. How come? Clippit, Dot and other MS Office characters weren't created to produce audible speech.
Where can I get more MS Agents? The [official Microsoft MS Agent site].
When I quit my program, I have to manually R-click Merlin to hide him. Is there any way to make Merlin hide upon completion of the program? If the SpeechClose() function isn't executed before the program ends, subsequent runs of the program will fail to hide the MS Agent. Be sure to include this function at the close of your program before closing the dll.
Where can I find all the comalspeech MS Agent commands? A complete list of animation, speak, think, move, show and resize functions is included with John's sample code included with the YoingcoDLLs.zip download. Additionally, you may be interested in the [Merlin tutorial] in the Liberty BASIC Newsletter Issue #126.
DEMO
The files msagentsDemo.bas and comalspeech.dll are included in the zipped archive of this newsletter.
::::::::::::::::::::::::::::::::::::::::::::::::::::
::::::::::::::::::::::::::::::::::::::::::::::::::::